home *** CD-ROM | disk | FTP | other *** search
/ Acorn Risc Technologies StrongARM CD-ROM / Acorn Risc Technologies StrongARM CD-ROM.iso / ftp / documents / appnotes / 231_245 / 237c / Text
Encoding:
Text File  |  1993-08-11  |  8.7 KB  |  258 lines
  1. -----------------------------------------------------------------------------
  2. 2nd August 1993
  3. -----------------------------------------------------------------------------
  4. Support Group Application Note
  5. Number: 237
  6. Issue:  Writing Wimp Module Tasks using Desktop C
  7. Author: James Bye
  8. -----------------------------------------------------------------------------
  9.  
  10.  
  11.  
  12. -----------------------------------------------------------------------------
  13. Applicable Hardware: All RISC OS computers.All RISC OS computers.
  14.  
  15. Related Application Notes:
  16.  
  17.  
  18. -----------------------------------------------------------------------------
  19. Copyright (C) Acorn Computers Limited 1992
  20.  
  21. Every effort has been made to ensure that the information in this leaflet is 
  22. true and correct at the time of printing. However, the products described in
  23. this leaflet are subject to continuous development and improvements and
  24. Acorn Computers Limited reserves the right to change its specifications at
  25. any time. Acorn Computers Limited cannot accept liability for any loss or
  26. damage arising from the use of any information or particulars in this
  27. leaflet. ACORN, ECONET and ARCHIMEDES are trademarks of Acorn Computers
  28. Limited.
  29. -----------------------------------------------------------------------------
  30. Support Group
  31. Acorn Computers Limited
  32. Acorn House
  33. Vision Park
  34. Histon
  35. Cambridge
  36. CB4 4AE                                                  
  37. -----------------------------------------------------------------------------
  38.  
  39.  
  40.  
  41.  
  42. This application outlines how to write Wimp Module Tasks using Desktop C.
  43.  
  44. Applicable Hardware:  All RISC OS computers.All RISC OS computers.
  45.  
  46.  
  47. 1. Introduction
  48.  
  49. This application note outlines how to write Wimp Module Tasks in C using the
  50. CMHG (C Module Header Generator) and presumes that the reader has experience
  51. of using Desktop and its associated libraries and utilities.
  52.  
  53. Although the creation of Wimp Module Tasks in C is relatively stimple, there
  54. are a few problem areas that need to be made clear to the programmer.  This
  55. application note covers the following areas :-
  56.  
  57.     - Overview of CMHG and constructing the header files
  58.     - Implementing simple the C routines defined in C header 
  59.     - Handling Service_Memory 
  60.     - Linking to RISC_OSLib 
  61.     - Compiling C source files 
  62.     - Details of other relevant documentation
  63.  
  64. A disc containing an example C Module task is included for reference with
  65. this application note.
  66.  
  67.  
  68. 2. Overview of CMHG and constructing the header file
  69.  
  70. Desktop C provides a tool called !CMHG (C Module Header Generator) for
  71. generating module headers for C modules.  CMHG produces a header that
  72. veneers onto your C program and this tool should always be used when
  73. constructing modules in C.  Producing your own header in assembly language
  74. is relatively complex and this is why CMHG has been provided.
  75.  
  76. The example on the enclosed disc is a simple example, and the CMHG file
  77. looks like the following :-
  78.  
  79.                  ; /*
  80.                  ;  * C Module Header for Capture 
  81.                  ;  */ 
  82.                  module-is-runnable: 
  83.                  ; /* 
  84.                  ;  * service call handler 
  85.                  ;  */
  86.                  service-call-handler: MyService 
  87.                  ; /* 
  88.                  ;  * title string 
  89.                  ;  */     title-string: Capture
  90.                  ; /* 
  91.                  ;  * help string 
  92.                  ;  */
  93.                  help-string: Capture 1.00
  94.  
  95. It is worth noting at this point that, when constructing C Module Tasks, the
  96. module must be runnable and implement a service call handler.  You will see
  97. from this example that not all the fundamental components of a C Module
  98. header have been implemented.  If you wish to claim RMA workspace using the
  99. OS_Module calls or claim vectors etc, then you will need to implement an
  100. initialisation routine.  Full details on how the other fundamental
  101. components of a C Module are implemented can be found in the Desktop C User
  102. Guide (Chapter 14, page 337).
  103.  
  104.  
  105. 3. Implementing C routines defined in Module Header
  106.  
  107. As shown in section 2, our simple example implements a runnable entry point
  108. and a service call handler.
  109.  
  110. When a module is runnable, the C entry interface is as follows :-
  111.  
  112.             int main ( int argc, char *argv[]);
  113.  
  114. Where the value argc is the number of arguments passed to the module and
  115. *argv is a pointer to the command line arguments.  In our example, the run
  116. entry for the module looks like the following :-
  117.  
  118.     int main ( void ) {
  119.  
  120.   wimpt_init("Capture");
  121.   task_handle = wimpt_task();
  122.   res_init("Capture");
  123.   resspr_init();
  124.   flex_init();
  125.   template_init();
  126.   dbox_init();
  127.   visdela y_init();
  128.  
  129.   event_setmask(wimp_EMPTRLEAVE | wimp_EMPTRENTER);
  130.  
  131. trace_on();
  132.  
  133.   iconbar_buffer = malloc(iconbar_buffer_len);
  134.   strcpy(iconbar_buffer,"Ready");
  135.  
  136.   iconbar_icon =baricon_textandsprite("!capture",iconbar_buffer,
  137.   iconbar_buffer_len,1,click_proc);
  138.  
  139.   iconbar_menu = menu_new(m_IconBar_Title,m_IconBar_Hits);
  140.       event_attachmenu(win_ICONBAR,iconbar_menu,iconbar_menu_events,NULL);
  141.  
  142. while(TRUE)
  143.       event_process(); 
  144.  
  145.       }
  146.  
  147.  
  148. The above is a simple application initialisation routine that is common to
  149. many applications written using RISC_OSLib.
  150.  
  151. It is worth noting that the runnable entry point for a module is entered in
  152. User Mode and not in SVC mode.  This means that any calls to malloc() in the
  153. main routine will cause memory to be allocated in the application workspace
  154. and not in the RMA.  If you wish to allocate RMA space in the main routine
  155. then you will need to call the relevant OS_Module SWI.
  156.  
  157. The C entry for Service Calls is as follows :-
  158.  
  159.     void service_handler( int service_number, _kernel_swi_regs *r, void *pw );
  160.  
  161. The service call handler for our example is covered more deeply in the next
  162. section.
  163.  
  164.  
  165. 4. Handling Service_Memory
  166.  
  167. When writing a module task in C, the service call Service_Memory (0x11)
  168. needs to be claimed.  The way to do this is as follows (this is also shown
  169. in our simple example) :-
  170.  
  171.             #define Service_Memory       0x11
  172.  
  173.             extern void MyService ( int service_number, _kernel_swi_regs *r,
  174.             void *pw )        
  175.             {
  176.                pw = pw;
  177.  
  178.               /*-- keep application workspace (r2 holds CAO pointer) */
  179.  
  180.               switch(service_number)
  181.               {
  182.                    case service_memory : if(r->r[2] == (int)Image__RO_Base)
  183.                                         {
  184.                                             /*--refuse to release app. workspace --*/    
  185.                                             r->r[1] = 0;
  186.                                         }
  187.                                         break;
  188.                }
  189.             }
  190.  
  191.  
  192. The service call handler needs to compare the contents of register R2 with
  193. the address of the base of you module containing it.  However, this is not a
  194. value directly available to C and the following assembler language fragment
  195. is used to gain access to the symbol |Image$$RO$$Base|.  The fragment is as
  196. follows :-
  197.  
  198.            IMPORT  |Image$$RO$$Base| 
  199.            EXPORT  Image__RO_Base
  200.  
  201.               AREA    Code_Description, DATA, REL 
  202.         Image__RO_Base        DCD     |Image$$RO$$Base|
  203.  
  204.              END
  205.  
  206.  
  207. This object can be found pre-assembled on the example disc.
  208.  
  209. One of the constraints of writing module tasks in C is that the module task
  210. will appear in the list of applications and not in the list of module tasks.
  211.  
  212.  
  213. 5. Linking to RISC_OSLib
  214.  
  215. If you are using RISC_OSLib in the construction of your C Module task, then
  216. you will need to link to a special version of RISC_OSLib that has been
  217. compiled as module code.  However, a module code version of RISC_OSLib is
  218. not supplied with Desktop C.  If you have the RISC_OSLib sources, then you
  219. can build a module version by entering your source directory and typing the
  220. following :-
  221.  
  222.     amu -f makemod
  223.  
  224. The relevant RISC_OSLib object can be found on the enclosed disc.
  225.  
  226.  
  227. 6. Compiling C source code
  228.  
  229. When compiling your C source code for inclusion in a module, then you must
  230. indicate to the C Compiler that you wish it to generate module code.  This
  231. can be done by either specifying the '-zM' option if you are compiling from
  232. the command line, or by selecting the module code option from the CC window. 
  233. The same applies when linking.
  234.  
  235.  
  236. 7. Other relevant documentation
  237.  
  238. This application note is intended only as an introduction to writing module
  239. tasks in C.  There are many relevant areas which are beyond the scope of
  240. this document.  It is therefore recommended that the reader consults the
  241. following manuals :-
  242.  
  243.  
  244. 1. The RISC OS 3 Programmer's Reference Manual
  245.  
  246. 2. The Acorn ANSI C Release 4 Manual
  247.  
  248. The RISC OS 3 Programmers Reference Manual contains detailed information and
  249. the Modules and Window Manager chapters should be read.  The Window Manager
  250. section contains information on  the service call Service_StartWimp (&49)
  251. which is important when writing module tasks that are permanently resident
  252. (Volume 3, page 70).
  253.  
  254.  
  255.  
  256.  
  257.  
  258.